# -*- coding: utf-8 -*-
# @Time    : 2024/7/4 16:51
# @Author  : yujiahao
# @File    : 02_fastapi_first_programmer.py
# @description: 使用概括


# 步骤 1：导入 FastAPI¶

from fastapi import FastAPI

'''
FastAPI 是一个为你的 API 提供了所有功能的 Python 类。

技术细节

    FastAPI 是直接从 Starlette 继承的类。   
    你可以通过 FastAPI 使用所有的 Starlette 的功能。
'''

# 步骤 2：创建一个 FastAPI「实例」¶
'''这里的变量 app 会是 FastAPI 类的一个「实例」。

这个实例将是创建你所有 API 的主要交互对象。

这个 app 同样在如下命令中被 uvicorn 所引用：
'''
app = FastAPI()

# 步骤 3：创建一个路径操作¶

'''
这里的「路径」指的是 URL 中从第一个 / 起的后半部分。「路径」也通常被称为「端点」或「路由」。

所以，在一个这样的 URL 中：https://example.com/items/foo
路径会是：/items/foo

在开发 API 时，通常使用特定的 HTTP 方法去执行特定的行为。在OpenAPI中每个HTTP方法都被称为【操作】，所以这里也叫操作
    POST：创建数据。
    GET：读取数据。
    PUT：更新数据。
    DELETE：删除数据。
    
所以这里定义一个路径操作装饰器 @app.get("/items/foo")
    - @something 语法在 Python 中被称为「装饰器」。
    - 像一顶漂亮的装饰帽一样，将它放在一个函数的上方（我猜测这个术语的命名就是这么来的）。
    - 装饰器接收位于其下方的函数并且用它完成一些工作。
    - 在我们的例子中，这个装饰器告诉 FastAPI 位于其下方的函数对应着路径 /items/foo 加上 get 操作。
    - 它是一个「路径操作装饰器」。
    
        也可以使用其他的操作：
            @app.post()
            @app.put()
            @app.delete()
        以及更少见的：          
            @app.options()
            @app.head()
            @app.patch()
            @app.trace()


就是告诉FastAPI在它下方的函数负责处理如下请求：
 1、请求路径为 /items/foo
 2、使用 get 操作
'''


@app.get("/items/foo")
def root():
    # 步骤 5：返回内容¶ （可以返回一个 dict、list，像 str、int 一样的单个值，还可以返回Pydantic 模型，等等）
    return {"message": "Hello FastAPI"}


'''
总结¶
    - 导入 FastAPI。
    - 创建一个 app 实例。
    - 编写一个路径操作装饰器（如 @app.get("/")）。
    - 编写一个路径操作函数（如上面的 def root(): ...）。
    - 运行开发服务器（如 uvicorn main:app --reload）。
'''
